/*_############################################################################
  _## 
  _##  SNMP4J 2 - MessageDispatcher.java  
  _## 
  _##  Copyright (C) 2003-2011  Frank Fock and Jochen Katz (SNMP4J.org)
  _##  
  _##  Licensed under the Apache License, Version 2.0 (the "License");
  _##  you may not use this file except in compliance with the License.
  _##  You may obtain a copy of the License at
  _##  
  _##      http://www.apache.org/licenses/LICENSE-2.0
  _##  
  _##  Unless required by applicable law or agreed to in writing, software
  _##  distributed under the License is distributed on an "AS IS" BASIS,
  _##  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  _##  See the License for the specific language governing permissions and
  _##  limitations under the License.
  _##  
  _##########################################################################*/
package org.snmp4j;

import org.snmp4j.smi.Address;
import org.snmp4j.mp.*;
import java.util.Collection;
import org.snmp4j.asn1.BERInputStream;
import org.snmp4j.transport.TransportListener;
import java.nio.ByteBuffer;

/**
 * The <code>MessageDispatcher</code> interface defines common services of
 * instances that process incoming SNMP messages and dispatch them to
 * interested {@link CommandResponder} instances. It also provides a service
 * to send out outgoing SNMP messages.
 * <p>
 * A <code>MessageDispatcher</code> needs at least one {@link TransportMapping}
 * and at least one {@link MessageProcessingModel} in order to be able to
 * process any messages.
 *
 * @author Frank Fock
 * @version 2.0
 */
public interface MessageDispatcher extends TransportListener {

  /**
   * Gets the next unique request ID. The returned ID is unique across
   * the last 2^31-1 IDs generated by this message dispatcher.
   * @return
   *    an integer value in the range 1..2^31-1. The returned ID can be used
   *    to map responses to requests send through this message dispatcher.
   * @since 1.1
   */
  int getNextRequestID();

  /**
   * Adds a {@link MessageProcessingModel} to the dispatcher. In order to
   * support a specific SNMP protocol version, the message dispatcher needs
   * a message processing model to process messages before they can be
   * dispatched.
   * @param model
   *    a <code>MessageProcessingModel</code> instance.
   */
  void addMessageProcessingModel(MessageProcessingModel model);

  /**
   * Removes a previously added {@link MessageProcessingModel} from
   * the dispatcher.
   * @param model
   *    a <code>MessageProcessingModel</code> instance.
   */
  void removeMessageProcessingModel(MessageProcessingModel model);

  /**
   * Gets the <code>MessageProcessingModel</code> for the supplied message
   * processing model ID.
   *
   * @param messageProcessingModel
   *    a message processing model ID
   *    (see {@link MessageProcessingModel#getID()}).
   * @return
   *    a MessageProcessingModel instance if the ID is known, otherwise
   *    <code>null</code>
   */
  MessageProcessingModel getMessageProcessingModel(int messageProcessingModel);

  /**
   * Adds a {@link TransportMapping} to the dispatcher. The transport mapping
   * is used to send and receive messages to/from the network.
   * @param transport
   *   a <code>TransportMapping</code> instance.
   */
  void addTransportMapping(TransportMapping transport);

  /**
   * Removes a previously added {@link TransportMapping} from
   * the dispatcher.
   * @param transport
   *    a <code>TransportMapping</code> instance.
   * @return
   *    the <code>TransportMapping</code> instance supplied if it
   * could be successfully removed, <code>null</code> otherwise.
   */
  TransportMapping removeTransportMapping(TransportMapping transport);

  /**
   * Gets the <code>Collection</code> of transport mappings in this message
   * dispatcher.
   * @return
   *    a Collection with the registered transport mappings.
   */
  Collection<TransportMapping> getTransportMappings();

  /**
   * Returns a transport mapping that can handle the supplied address.
   * @param destAddress
   *    an Address instance.
   * @return
   *    a <code>TransportMapping</code> instance that can be used to sent
   *    a SNMP message to <code>destAddress</code> or <code>null</code> if
   *    such a transport mapping does not exists.
   * @since 1.6
   */
  TransportMapping getTransport(Address destAddress);

  /**
   * Adds a {@link CommandResponder} instance to the message dispatcher.
   * Successfully processed SNMP messages will be presented to all command
   * responder (in the order in which they have been added) until a responder
   * uses the {@link CommandResponderEvent#setProcessed(boolean processed)}
   * to set the processed status of the event to <code>true</code>.
   * @param listener
   *    a <code>CommandResponder</code> instance.
   */
  void addCommandResponder(CommandResponder listener);

  /**
   * Removes a previously added {@link CommandResponder} instance from
   * the message dispatcher.
   * @param listener
  *    a <code>CommandResponder</code> instance.
   */
  void removeCommandResponder(CommandResponder listener);

  /**
   * Sends a PDU to the supplied transport address.
   * @param transportMapping
   *    the <code>TransportMapping</code> to be used to send the PDU. If
   *    <code>transportMapping</code> is <code>null</code> the message
   *    dispatcher will determine the appropriate transport mapping for the
   *    given transport address.
   * @param target
   *    the target which identifies, transport address, message processing model,
   *    security model, security name and level.
   * @param pdu
   *    the SNMP Protocol Data Unit
   * @param expectResponse
   *    <code>true</code> if a response is expected and a state reference should
   *    be saved (if needed for the supplied message processing model).
   * @return
   *    an <code>PduHandle</code> that uniquely identifies this request.
   * @throws MessageException
   */
  PduHandle sendPdu(TransportMapping transportMapping,
                    Target target,
                    /* the following parameters are given in ScopedPDU
                       byte[] contextEngineID,
                       byte[] contextName,
                     */
                    PDU pdu,
                    boolean expectResponse) throws MessageException;

  /**
   * Sends a PDU to the supplied transport address and returns the
   * <code>PduHandle</code> that uniquely identifies the request as response
   * <em>after<em> the request has been sent and optional, if a
   * {@link PduHandleCallback} is given, it returns also the
   * <code>PduHandle</code> just <em>before<em> the request is sent through the
   * the callback interface.
   *
   * @param transportMapping
   *    the <code>TransportMapping</code> to be used to send the PDU. If
   *    <code>transportMapping</code> is <code>null</code> the message
   *    dispatcher will determine the appropriate transport mapping for the
   *    given transport address.
   * @param target
   *    the target which identifies, transport address, message processing model,
   *    security model, security name and level.
   * @param pdu
   *    the SNMP Protocol Data Unit
   * @param expectResponse
   *    <code>true</code> if a response is expected and a state reference should
   *    be saved (if needed for the supplied message processing model).
   * @param callback
   *    an optional callback instance that is informed (if not
   *    <code>null</code>) about the newly assigned PduHandle just before the
   *    message is sent out.
   * @return
   *    an <code>PduHandle</code> that uniquely identifies this request.
   * @throws MessageException
   */
  PduHandle sendPdu(TransportMapping transportMapping,
                    Target target,
                    /* the following parameters are given in ScopedPDU
                       byte[] contextEngineID,
                       byte[] contextName,
                     */
                    PDU pdu,
                    boolean expectResponse,
                    PduHandleCallback<PDU> callback) throws MessageException;

  /**
   * Sends a PDU to the supplied transport address. This method behaves like
   * a call to {@link #sendPdu(TransportMapping transportMapping, Target target,
   * PDU pdu, boolean expectResponse)}
   * with <code>transportMapping</code> set to <code>null</code>.
   *
   * @param target
   *    the target which identifies, transport address, message processing model,
   *    security model, security name and level.
   * @param pdu
   *    the SNMP Protocol Data Unit
   * @param expectResponse
   *    <code>true</code> if a response is expected and a state reference should
   *    be saved (if needed for the supplied message processing model).
   * @return
   *    an <code>PduHandle</code> that uniquely identifies this request.
   * @throws MessageException
   */
  PduHandle sendPdu(Target target,
                    /* the following parameters are given in ScopedPDU
                       byte[] contextEngineID,
                       byte[] contextName,
                     */
                    PDU pdu,
                    boolean expectResponse) throws MessageException;

  /**
   * Returns a response PDU to the sender of the corresponding request PDU.
   *
   * @param messageProcessingModel int
   * @param securityModel int
   * @param securityName byte[]
   * @param securityLevel int
   * @param pdu PDU
   * @param maxSizeResponseScopedPDU int
   * @param stateReference StateReference
   * @param statusInformation StatusInformation
   * @throws MessageException
   *   if message processing fails with a fatal error.
   * @return
   *   an MP error status or {@link SnmpConstants#SNMP_MP_OK} if
   *   the operation was successful.
   */
  int returnResponsePdu(int messageProcessingModel,
                        int securityModel,
                        byte[] securityName,
                        int securityLevel,
                        /* the following parameters are given in ScopedPDU
                           byte[] contextEngineID,
                           byte[] contextName,
                         */
                        PDU pdu,
                        int maxSizeResponseScopedPDU,
                        StateReference stateReference,
                        StatusInformation statusInformation)
       throws MessageException;

  /**
   * Process an incoming SNMP message. The message is processed and dispatched
   * according to the message's content, the message processing models, and the
   * command responder available to the dispatcher.
   * @param sourceTransport
   *    a <code>TransportMapping</code> instance denoting the transport that
   *    received the message and that will be used to send any responses to
   *    this message. The <code>sourceTransport</code> has to support the
   *    <code>incomingAddress</code>'s implementation class.
   * @param incomingAddress
   *    the <code>Address</code> from which the message has been received.
   * @param wholeMessage
   *    an <code>ByteBuffer</code> containing the received SNMP message.
   * @param tmStateReference
   *    the transport model state reference as defined by RFC 5590.
   */
  void processMessage(TransportMapping sourceTransport,
                      Address incomingAddress,
                      ByteBuffer wholeMessage,
                      TransportStateReference tmStateReference);


  /**
   * Release any state references associated with the supplied
   * <code>PduHandle</code> in the specified message processing model.
   * @param messageProcessingModel
   *    a message processing model ID.
   * @param pduHandle
   *    the <code>PduHandle</code> that identifies a confirmed class message.
   * @see MessageProcessingModel
   */
  void releaseStateReference(int messageProcessingModel,
                             PduHandle pduHandle);
}

